---
title: "Reference: LangfuseExporter | Observability"
description: Langfuse exporter for Tracing
---

import PropertiesTable from "@site/src/components/PropertiesTable";

# LangfuseExporter

Sends Tracing data to Langfuse for observability.

## Constructor

```typescript
new LangfuseExporter(config: LangfuseExporterConfig)
```

## LangfuseExporterConfig

```typescript
interface LangfuseExporterConfig extends BaseExporterConfig {
  publicKey?: string;
  secretKey?: string;
  baseUrl?: string;
  realtime?: boolean;
  options?: any;
}
```

Extends `BaseExporterConfig`, which includes:
- `logger?: IMastraLogger` - Logger instance
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)

<PropertiesTable
  props={[
    {
      name: "publicKey",
      type: "string",
      description: "Langfuse API key",
      required: false,
    },
    {
      name: "secretKey",
      type: "string",
      description: "Langfuse secret key",
      required: false,
    },
    {
      name: "baseUrl",
      type: "string",
      description: "Langfuse host URL",
      required: false,
    },
    {
      name: "realtime",
      type: "boolean",
      description: "Enable realtime mode - flushes after each event",
      required: false,
    },
    {
      name: "logLevel",
      type: "'debug' | 'info' | 'warn' | 'error'",
      description: "Logger level (default: 'warn')",
      required: false,
    },
    {
      name: "options",
      type: "any",
      description: "Additional Langfuse client options",
      required: false,
    },
  ]}
/>

## Methods

### exportTracingEvent

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

Exports a tracing event to Langfuse.

### export

```typescript
async export(spans: ReadOnlySpan[]): Promise<void>
```

Batch exports spans to Langfuse.

### shutdown

```typescript
async shutdown(): Promise<void>
```

Flushes pending data and shuts down the client.

## Usage

```typescript
import { LangfuseExporter } from "@mastra/langfuse";

const exporter = new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: "https://cloud.langfuse.com",
  realtime: true,
});
```

## Span Mapping

- Root spans → Langfuse traces
- `MODEL_GENERATION` spans → Langfuse generations
- All other spans → Langfuse spans
- Event spans → Langfuse events

## Prompt Linking

Link LLM generations to [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management) using the `withLangfusePrompt` helper:

```typescript
import { buildTracingOptions } from "@mastra/observability";
import { withLangfusePrompt } from "@mastra/langfuse";
import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
});

const prompt = await langfuse.getPrompt("customer-support");

const agent = new Agent({
  name: "support-agent",
  instructions: prompt.prompt,
  model: openai("gpt-4o"),
  defaultGenerateOptions: {
    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
  },
});
```

### Helper Functions

#### `withLangfusePrompt(prompt)`

Adds Langfuse prompt metadata to tracing options.

```typescript
// With Langfuse SDK prompt object
withLangfusePrompt(prompt)

// With manual fields
withLangfusePrompt({ name: "my-prompt", version: 1 })
withLangfusePrompt({ id: "prompt-uuid" })
```

When `metadata.langfuse.prompt` is set on a `MODEL_GENERATION` span (with either `id` alone, or `name` + `version`), the exporter automatically links the generation to the prompt in Langfuse.
